home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / documents / Dwarf / README < prev   
Encoding:
Text File  |  1996-11-11  |  6.6 KB  |  167 lines
  1.  
  2.                             Dwarf documentation
  3.  
  4. ----------------------------------------------------------------------------
  5.  
  6.                IRIX 6.2-based versions of Dwarf documentation
  7.  
  8. For further reference, see also toolbox/FAQs/SGIfaqs/Dwarf-faq, and the IRIX
  9. 6.2-based libdwarf src subtree in toolbox/src/swtools/libdwarf.
  10.  
  11. DWARF is a binary debugging-information-format. It defines, in detail, a way
  12. for compilers to tell debuggers about source programs.
  13.  
  14. DWARF1 is the DWARF produced by USL's SVR4 compilers and used by their
  15. debuggers. It is no more capable than the MIPS mdebug symbol table and is
  16. less dense than mdebug. We will not use DWARF1.
  17.  
  18. SGI will be using DWARF 2. It is capable of recording much more detailed
  19. information than DWARF 1 and is far more compact (debugging information in
  20. DWARF2 format takes much less space on disk than debugging information in
  21. DWARF1 format).
  22.  
  23.                        -------------------------------
  24.  
  25.             All documentation included here comes from IRIX 6.2.
  26.                Everything besides the man pages lives in the
  27.                      compiler_dev.src.dwarf subsystem.
  28.  
  29.    * txt version of dwarf(4) man page
  30.    * txt version of libdwarf(4) man page
  31.    * txt version of dwarfdump man page
  32.  
  33.    * COPYING
  34.    * LIBDWARFCOPYRIGHT
  35.    * README.dwarf
  36.  
  37.    * dwarf.v2.ps.Z: DWARF Debugging Information Format, 108 pages
  38.      (dwarf.v2.mm troff src)
  39.  
  40.      FOREWARD
  41.  
  42.      This document specifies the second generation of symbolc debugging
  43.      information based on the DWARF format that has been developed by the
  44.      UNIX International Programming Languages Special Interest Group (SIG).
  45.      It is being circulated for industry review. The first version of the
  46.      DWARF specification was published by UNIX International in January,
  47.      1992. The current version adds significant new functionality, but its
  48.      main thrust is to acheive a much denser encoding the DWARF information.
  49.      Because of the new encoding, DWARF version 2 is not binary compatible
  50.      with DWARF version 1.
  51.  
  52.      As this point, the SIG believes that this document sufficiently
  53.      supports the debugging needs of C, C++, FORTRAN 77, Fortran90, Modula2,
  54.      and Pascal, and we have released it for public comment. We will accept
  55.      comments on this document until September 30, 1994. Comments may be
  56.      directed via email to the SIG mailing list (plsig@ui.org). If you are
  57.      unable to send email, paper mail, FAX, or machine readable copy on
  58.      UNIX, MS-DOS, or Macintosh compatible media can be sent to UNIX
  59.      International at the address listed below, and wil be forwarded to the
  60.      SIG.
  61.                               UNIX International
  62.                               Waterview Corporate Center
  63.                               20 Waterview Boulevard
  64.                               Parsippany, NJ 07054
  65.                               Phone: +1 201-263-8400
  66.                               Fax: +1 201-263-8401
  67.                NOTE: Table of Contents is on page 105,
  68.                List of Figures is on page 107
  69.                108 pages
  70.  
  71.    * index.v2.ps.Z: 3-page index
  72.      (index.v2.mm troff src)
  73.  
  74.    * libdwarf2.1.ps.Z: A Consumer Library Interface to DWARF
  75.      (libdwarf2.1.mm troff src)
  76.  
  77.      ABSTRACT:
  78.  
  79.      This document describes an interface to a library of functions to
  80.      access DWARF debugging information entries and DWARF line number
  81.      information. It does not make recommendations as to how the functions
  82.      described in this document should be implemented nor does it suggest
  83.      possible optimizations.
  84.  
  85.      The document is oriented to reading DWARF version 2. There are certain
  86.      sections which are SGI-specific (those are clearly indentified in the
  87.      document). We intend to propose this to the PLSIG committee as the
  88.      basis for a standard libdwarf interface.
  89.  
  90.      The proposals made in this document are subject to change.
  91.  
  92.      47 pages
  93.      NOTE: CONTENTS is on page 45
  94.           LIST OF FIGURES is on page 46
  95.           ABSTRACT is on page 47
  96.  
  97.    * libdwarf2p.1.ps.Z: A Producer Library Interface to DWARF
  98.      (libdwarf2p.1.mm troff src)
  99.  
  100.      17 pages
  101.      NOTE: CONTENTS is on page 16
  102.  
  103.            ------------------------------------------------------
  104.  
  105.    from the toolbox/FAQs/SGIfaqs/Dwarf-faq file:
  106.  
  107.      4) An Overview of Dwarf Information Content
  108.  
  109.      The documents mentioned in section 3 are long on details and short on
  110.      overview. Lets try to put this all in to a total picture.
  111.  
  112.      To represent Debugging Information in an a.out we need several quite
  113.      different categories of information spread across various ELF object
  114.      file sections.
  115.  
  116.      A. Information about code and data variables.
  117.         DWARF information is a tree of Debugging Information
  118.         Entries (DIEs).  Each tree entry (Die) has a TAG which
  119.         identifies what type of entry it is and Attributes
  120.         which give the details.  DIEs at the global level in a
  121.         compilation unit are tied together with Sibling Pointers.
  122.         Siblings are equal-level DIEs.
  123.         Children, on the other hand, are *owned* DIEs.
  124.         Lets adopt the following symbols for DIE relationships:
  125.             Sibling pointer  ->
  126.  
  127.             Child pointer    |
  128.                              v
  129.  
  130.         Here is a representation of the DIEs for t.c where types
  131.         are left out to keep things simple (they don't change
  132.         this, they are just more DIEs to clutter things up):
  133.         t.c:
  134.             int foo(int i, int j) {  return 3;}
  135.             int goo;
  136.  
  137.             Compilation_Unit
  138.                     |
  139.                     v
  140.                     function "foo"   -> global variable "goo "
  141.                     |
  142.                     v
  143.                     parameter "i"    -> parameter "j"
  144.  
  145.           This goes in the .debug_info section with a tiny amount
  146.           of supporting data in .debug_abbrev
  147.      B. Information about the mapping from code addresses to source
  148.         A separate section holds a very compact mapping from
  149.         code addresses to source lines (and columns).
  150.           This is in the .debug_line section.
  151.      C. Information about C Macros
  152.         If desired, all C Macro #defines and #undef-s and
  153.         #includes are recorded, with
  154.         the mapping back to the source files.
  155.           This is in the .debug_macinfo section.
  156.      D. Information about unwinding stack frames
  157.         This is specially recorded in a section of its own: a
  158.         seperate small string of bytes per function/procedure.
  159.           This is in the .debug_frame section.
  160.  
  161.  
  162.      Other .debug_* sections are for supporting data or for fast access to
  163.      global names, types, and statics.
  164.  
  165. ----------------------------------------------------------------------------
  166.  
  167.